docs(skills): a suite composes under manifest preserve; a flat composition of two apps under one package is refused - #33475

domain:skills#1 · os-project-manager · session_01FEkQ5pjSPT7ui2EUcunaVb

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f4fc5ea9ef745844ea53e28ac399fa53f8f62f17
Local-runs: none
Scope: skills/objectstack-platform/references/bootstrap.md, skills/objectstack-ui/SKILL.md + none

Read on origin/main (the PR's base 34c05229; main has since moved to b5f2f516, which touches none of these files and not packages/spec/src/stack.zod.ts): composeStacks, composeBuiltStacks, ComposeStacksOptionsSchema.manifest, SINGLE_APP_PACKAGE_TYPES, SINGLE_APP_COMPOSE_REMEDY, singleAppFinding, validateSingleApp, collectComposedSingleAppErrors, flatSingleAppFinding, residualSingleAppFinding, StackRefusalError, StackSingleAppViolationError; examples/app-multi-package/objectstack.config.ts and its two packages; docs/adr/0019-app-as-consumer-unit.md; card #32977 with every comment (fold 6846119916, dev report 6884932864); card #33135 with its comment.

① Derived judgments

• Accept set: none moves. The diff is skill prose and a changeset; no schema, no runtime, no gate script. What the prose teaches is checked against the accept set that is already on main (④).
• Public surface: the @objectstack/skills published text only (two files). Right.
• Gates: the head's check-runs are the verdicts. At review 18 completed success, 18 skipped, none failed, and 9 still in progress (Lint · docs & code guards, Lint · repo & tooling gates, Lint · CI, release & engine gates, Lint · ESLint, Check Changeset, Type Check · source gates, Type Check · consumer gates, Test Core (1/8), Test Core (2/8)). The token and line ratchets and the skill-doc checks ride the lint lanes still running; the merge waits on them green. This record does not stand in for them.

② Semver level

• .changeset/32977-skills-suite-composes-under-preserve.md: '@objectstack/skills': patch. Matches the repo's convention for skill-text corrections (the last five docs(skills) merges on main carry the same line). Right.
• Clause-②: no on the PR body and the changeset: no published key is added, removed or narrowed. Right. Metadata-protocol: none: right.

③ Boundary flags

• open_questions: empty.
• Deviation, ADR-0019 left to docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135: right. Fold 6846119916 row 2 and docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 name one sentence of ADR-0019's "Enforced for modules" note ("Two shapes are not judged ... a flat composeStacks ... and a hand-built packages[] body"), a governed ADR surface, and one sentence wants one owner. Escalated, not a finding on this diff: docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135's Expected names only the hand-built body half, and this PR carries Fixes #32977, so the merge closes the card that holds row 2. The seat writes onto docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135, before or at this merge, that the flat-composition half of the sentence is false too since PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898 and the PR for docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 rewrites the whole sentence; otherwise row 2 is lost.
• Deviation, resolveArtifactCollections not taught: right. 6846119916 says the remedy "can" name it; the card's Work asks for the preserve remedy, and an author composes with composeStacks, not with the runtime reader.
• Deviation, no HTML-comment trailer, model-free commit trailer, no merge of the moved main: process lines for the seat; none bears on the contract.
• Deviation, the in-file cuts: judged in ④.

④ Design judgment

skills/objectstack-platform/references/bootstrap.md, § Multi-App Composition, against the card's Work items 1 and 2 and stack.zod.ts on main:

• "A suite (an app package plus module packages, one app each) composes with composeStacks(stacks, { manifest: 'preserve' }), which keeps each package's own id": holds. SINGLE_APP_COMPOSE_REMEDY says the same words; under 'preserve' each input with a manifest is assembled into a body of its own and registered under its own id, so a one-app-per-package suite leaves no residual app (collectComposedSingleAppErrors doc). The qualifier "one app each" with each being a package is what keeps the residual rule from biting, so the sentence does not over-promise.
• "(examples/app-multi-package)": holds. Line 68 of the config is composeStacks([ordersStack, coreStack], { manifest: 'preserve' }), and the two inputs are a type: 'app' package (com.example.multi.core) and a type: 'module' package (com.example.multi.orders). The old "No app in this repo uses it" is gone. Work item 2 done.
• "A flat manifest ('last', the default, 'first' or an index) keeps one": holds. The schema is z.union([z.enum(['first', 'last', 'preserve']), z.number().int().min(0)]).default('last'); the three non-preserve values are the pick-one set the option doc names.
• "so two or more apps under one app or module package id are refused": holds on the exact condition. flatSingleAppFinding refuses when the composed manifest's type is in SINGLE_APP_PACKAGE_TYPES (app, module) and the composed apps holds more than one entry; a kept manifest of any other type, or one app in all, passes. The sentence names both the package-type gate and the count.
• "(STACK_SINGLE_APP_VIOLATION, 422)": holds. StackSingleAppViolationError.code = 'STACK_SINGLE_APP_VIOLATION', status = 422 from StackRefusalError, thrown by composeBuiltStacks on the collectComposedSingleAppErrors result. Work item 1 done.
• Tried to break it: a single input (stacks.length === 1 returns it untouched) is not a composition and not a suite; a flat composition whose input carries packages[] is judged by the residual rule instead, and is still refused in the case the sentence describes; under 'preserve' an input with no manifest can still be refused (residual app). None of these makes a taught sentence false: the text claims nothing about them.
• The first paragraph's cuts ("this is how real multi-app composition happens", "equal the physical table name") lose no rule: the table-name rule stands in objectstack-platform/SKILL.md § Object naming ("equals the physical table name"), and "globally unique name" plus "use it directly" keep the instruction.
• Other cuts ("(moved verbatim from SKILL.md)", "(traditional)", "(key becomes name) ... for readability", "Use barrel exports to keep config clean:", "A minimal but complete project from scratch:", the stack.zod.ts pointer): each restates its heading, the sentence above the block, or references/_index.md (which lists stack.zod.ts). "read the schema before reaching for it" went with the false claim it hedged. No other file in the tree quotes the removed title or sentence. No rule lost.

skills/objectstack-ui/SKILL.md, § App Navigation, against fold 6846119916 row 1:

• "the suite composes with composeStacks(stacks, { manifest: 'preserve' }), which serves each app under its own package id; a flat composition puts them under one and is refused": holds. It is SINGLE_APP_COMPOSE_REMEDY ("a flat composition puts every app back under one") in the section's words; in a suite the kept manifest is an app or module package, so the unqualified "is refused" is true for the case the paragraph is about. "served under that module's package id" folded into "serves each app under its own package id", and "gone when it is disabled" is kept. Row 1 done.
• requiresObject / requiresService note shortened: the behaviour (an item hides when the optional object or service is missing) and the prohibition ("never hard-code conditional UI") both stay. No rule lost.
• Finding 1, nit: the subforms example's comment cut removes this file's only mention of the relationshipField key. The behaviour stays taught (the paragraph under the list: "The relationship FK and grid columns are derived from the child object's metadata in every case"), the old comment taught no FK override either, and the key is taught in objectstack-data/rules/relationships.md and objectstack-ui/rules/pages.md. No effect on correctness; accepted as a deviation.

No must-fix, no should-fix. One nit, accepted. The ADR-0019 relay onto #33135 is the seat's (③), not this diff's.

Implemented-by: claude/project-thread-rqofat
Reviewed-by: session_01FEkQ5pjSPT7ui2EUcunaVb

VERDICT: PASS

_{Adopted by the seat 2026-11-14T22:27Z · isolated sub-agent at CONTRACT_REVIEW_TIER · Ruling-ref: Leehom card cmsg_01TenzsRopZj4jMbvjX8uz1XFhuiZmTH8VFgMmHRmpiGAb, option A, tapped 2026-11-14T15:37Z}

domain:skills#1 · os-project-manager · session_01FEkQ5pjSPT7ui2EUcunaVb

维护者速读

• 改了什么:objectstack-platform 的 bootstrap 参考“多应用组合”一节写明：套件要用 composeStacks(stacks, { manifest: 'preserve' }) 组合;扁平选项('last' 默认、'first'、下标)在一个 app/module 包下会出现两个以上应用时被拒(STACK_SINGLE_APP_VIOLATION,422)。删掉“本仓没有应用用 preserve”这句错话(examples/app-multi-package 就在用)。objectstack-ui 技能的 App Navigation 一节补上同一处方。外加 patch changeset。
• 为什么改:PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898 让扁平组合被拒，技能还在教旧写法，AI 照着写会白跑一轮(卡 skills: bootstrap.md teaches composeStacks without saying a suite composes under manifest 'preserve', now that a flat composition with two or more apps under one app or module package is refused #32977)。
• 风险与回滚：只改技能文字，不动 schema 与运行时;两个文件都在原文件内删冗余腾出 token,未抬上限。回滚即还原本 PR。
• 先看:skills/objectstack-platform/references/bootstrap.md 的 Multi-App Composition,再看 skills/objectstack-ui/SKILL.md 的 App Navigation。
• 两分钟验证:git diff origin/main -- skills/。
• 需要你做的：受管面 Tier H(skills/**),契约复审 PASS 评论 6885186638(Head-sha f4fc5ea9ef745844ea53e28ac399fa53f8f62f17)已在案，请批准或直接合并。
• 席位意见：可以合。复审逐句对照 stack.zod.ts 的拒绝条件、选项、状态码与处方，均成立;删减没有丢规则。ADR-0019 里同一句旧话留给 docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 一并改(席位已在该卡注明要整句重写)。

席位核对

Verdict: ACCEPT, held for the maintainer · head f4fc5ea9ef745844ea53e28ac399fa53f8f62f17 · card #32977 · report 6884932864 · contract review 6885186638 (PASS on this head, CONTRACT_REVIEW_TIER; Ruling-ref for the in-seat review: Leehom card cmsg_01TenzsRopZj4jMbvjX8uz1XFhuiZmTH8VFgMmHRmpiGAb option A).

• Shape: draft → main, Fixes #32977. skills/objectstack-platform/references/bootstrap.md, skills/objectstack-ui/SKILL.md (the folded row of 6846119916), one '@objectstack/skills': patch changeset. GOVERNED, Tier H (skills/**). Clause-②: no; Metadata-protocol: none.
• Contract: flatSingleAppFinding refuses only when the kept manifest is app or module (SINGLE_APP_PACKAGE_TYPES) and the composed apps has more than one entry; the flat set is 'last' (default), 'first', an index; StackSingleAppViolationError is 422; both new sentences match SINGLE_APP_COMPOSE_REMEDY. examples/app-multi-package/objectstack.config.ts composes with { manifest: 'preserve' }.
• Token payments: bootstrap 1340 / 1343, objectstack-ui 3809 / 3814, no ceiling moved. No taught rule lost; the cut facts live on in objectstack-platform/SKILL.md and references/_index.md.
• Gates: 48 derived, 46 exit 0, 2 NOT MEASURED (no package touched). Check-runs on the head all concluded, none failing.
• ADR-0019 fold row: left to docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135, which owns the same sentence. Merging this PR closes skills: bootstrap.md teaches composeStacks without saying a suite composes under manifest 'preserve', now that a flat composition with two or more apps under one app or module package is refused #32977, so the seat noted on docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 that the whole sentence is false since PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898 (both halves), and the fix rewrites it entire.
• Accepted deviation (review nit): the cut subforms comment was the file's only mention of relationshipField; the paragraph below still says the foreign key is derived, and the key is taught in objectstack-data/rules/relationships.md and objectstack-ui/rules/pages.md.
• Process: the thread ran at the default tier, met by this in-seat review.
• Landing: Tier H. The seat does not flip this PR ready or enqueue it. It needs the maintainer's merge, or an authorised APPROVED review after which the seat lands it.

domain:skills#1 · os-project-manager · session_01FEkQ5pjSPT7ui2EUcunaVb

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f4fc5ea9ef745844ea53e28ac399fa53f8f62f17
Local-runs: none
Scope: skills/objectstack-platform/references/bootstrap.md, skills/objectstack-ui/SKILL.md + none

At-tier re-review of this head. The earlier record 6885186638 is not used as evidence; ③ says which of its findings stand. Read for this record: card #32977 with every comment, the PR body and file list, the net diff against main (merge base 34c05229), the check-runs on the head, and, in the live tree on origin/main 8e63ed87, packages/spec/src/stack.zod.ts (SINGLE_APP_PACKAGE_TYPES, SINGLE_APP_COMPOSE_REMEDY, singleAppFinding, validateSingleApp, collectComposedSingleAppErrors, flatSingleAppFinding, residualSingleAppFinding, ComposeStacksOptionsSchema.manifest, StackRefusalError, StackSingleAppViolationError), examples/app-multi-package/objectstack.config.ts and its two packages, skills/objectstack-platform/SKILL.md, skills/objectstack-platform/references/_index.md, scripts/sync-scaffold-emission-policy.mjs. main moved 98 files past the merge base; none is stack.zod.ts, either hits file, the example, or a ratchet script.

① Derived judgments

• Accept set: none moves. The diff is two skill prose files and one changeset; no schema, runtime or gate script. Right.
• Public surface: the published text of @objectstack/skills (two files). Right.
• Gates: every check-run on the head is completed; none failed, cancelled or timed out. Success includes Lint · docs & code guards, Lint · repo & tooling gates, Lint · CI, release & engine gates, Lint · scoped · tooling self-tests, Check Changeset (3), Governed Surface Queue Guard (2), PR-body guards, Type Check · workspace, Test Core (1/8), Test Core (2/8), Test Core, Build Core. The skipped runs are the UI, docs-build and opt-in lanes this path set does not derive. The token and line ratchets, skill-doc, skill-link and scaffold-policy checks are answered by those lint lanes; nothing was re-run here.

② Semver level

• .changeset/32977-skills-suite-composes-under-preserve.md: '@objectstack/skills': patch. The package name is the one in packages/skills/package.json; patch is what a teaching-text correction publishes and is what the newest docs(skills) merge on main (docs(skills): the security rules teach a position rename through renamedFrom #33480) carries. Right.
• Clause-②: no, on the PR body and in the changeset. Right: no published key is added, removed or narrowed; the refusal the text describes landed with PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898, not here. Metadata-protocol: none: right.

③ Boundary flags

• open_questions: empty.
• ADR-0019 row (fold 6846119916 row 2) left out of this diff: accepted. The row is a governed ADR sentence the claim assigns to docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135. Escalated to the seat, not a finding on this diff: this PR carries Fixes #32977, so the merge closes the card that holds row 2; the row survives only if docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 says the whole sentence (the flat-composition half as well as the hand-built packages[] half) is false since PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898. docs: ADR-0019's enforcement log still lists a hand-built packages[] body as not judged, after #33074 and #33122 #33135 is outside this review's inputs and was not read; the seat confirms that note before the merge.
• resolveArtifactCollections not taught: accepted. 6846119916 says the remedy can name it, the card's Work does not ask for it, and an author composes with composeStacks.
• In-file token payments: judged in ④; no ceiling moved.
• No HTML-comment trailer, model-free commit trailer, no merge of the moved main, thread ran at the default tier: process lines for the seat; none bears on the contract. The tier is met by this record.
• Earlier record 6885186638: its ④ sentence-by-sentence readings are confirmed against the tree. Its one nit (the relationshipField mention) is confirmed as a nit. It raised no should-fix or must-fix, so nothing was owed a fix on this head. Its ① listed 9 runs in progress; all have since concluded success. It missed the nit below on what the cited example shows.

④ Design judgment

skills/objectstack-platform/references/bootstrap.md, § Multi-App Composition, against card Work items 1 to 3 and stack.zod.ts:

• "A suite (an app package plus module packages, one app each) composes with composeStacks(stacks, { manifest: 'preserve' }), which keeps each package's own id": holds. It is SINGLE_APP_COMPOSE_REMEDY and the manifest option's own doc ("A suite — an app package plus module packages, each with an app of its own — composes under 'preserve'"). Under 'preserve' each input with a manifest is assembled into its own packages[] body, each judged by its own type, id and apps.
• "A flat manifest ('last', the default, 'first' or an index) keeps one": holds. The schema is the union of 'first', 'last', 'preserve' and a non-negative integer, default 'last'.
• "so two or more apps under one app or module package id are refused (STACK_SINGLE_APP_VIOLATION, 422)": holds on the exact condition. collectComposedSingleAppErrors gates on the kept manifest's type being in SINGLE_APP_PACKAGE_TYPES (app, module); flatSingleAppFinding refuses when the composed apps has more than one entry; the throw is StackSingleAppViolationError (code STACK_SINGLE_APP_VIOLATION, status 422 from StackRefusalError). Work item 1 done.
• "No app in this repo uses it" is gone; examples/app-multi-package/objectstack.config.ts ends composeStacks([ordersStack, coreStack], { manifest: 'preserve' }). Work item 2 done. Work item 3: PR feat(spec)!: composeStacks refuses a flat composition that puts two or more apps under one app or module package id, and every packages[] body is held to one app #32898 is on main; the text teaches only what the live tree does.
• Tried to break it. A flat composition whose kept manifest is neither app nor module, or that carries one app in all, passes: the sentence names both conditions, so it does not over-claim. A flat composition with an input carrying packages[] goes through the residual judge and is still refused in the case described. Under 'preserve' an input with no manifest can leave a residual app and be refused: the text says "package", and a package has a manifest, so no taught sentence is false. A single input is returned untouched and is not a composition.
• Cuts. "equal the physical table name" stands in objectstack-platform/SKILL.md § Object naming. The stack.zod.ts pointer stands in references/_index.md. The title's "(moved verbatim from SKILL.md)", the two heading restatements and the two Map Format comment glosses carry no rule. sync-scaffold-emission-policy anchors on the ## Complete Working Example heading and the package.json label, both kept. No rule lost.
• Finding 1, nit: the parenthetical examples/app-multi-package sits in the sentence whose subject is a suite with "one app each", but the example's module (com.example.multi.orders, type: 'module') defines no app; it adds to the core app through navigationContributions. The citation is true for what it is attached to (composing with 'preserve', each package keeping its id), and no taught sentence is false, but a reader opening it for a module that owns an app will not find one. Likewise "one app each" is narrower than the rule (at most one; a module with none composes the same way). No effect on correctness; left as an accepted deviation or a prose follow-up.

skills/objectstack-ui/SKILL.md, § App Navigation, against fold 6846119916 row 1:

• "the suite composes with composeStacks(stacks, { manifest: 'preserve' }), which serves each app under its own package id; a flat composition puts them under one and is refused": holds. In the suite the paragraph is about, the kept manifest is an app or module package and the apps number two or more, which is exactly the flatSingleAppFinding condition, so the unqualified "is refused" is true there. Row 1 done.
• "(gone when it is disabled)" moved into a parenthesis after "the objects it shows": still true of the app and of the module's objects alike. No rule lost.
• requiresObject / requiresService note: the behaviour and the "never hard-code conditional UI" prohibition both stay.
• Finding 2, nit: the subforms comment cut removes this file's only mention of relationshipField. The paragraph under the list still says the FK and grid columns are derived in every case, and the key is taught in objectstack-data/rules/relationships.md and objectstack-ui/rules/pages.md. No effect on correctness; accepted deviation.

The card carries no eval prompt and asks for none; the scenario judged against is the card's own (an agent composing a suite). No must-fix, no should-fix. Two nits, neither needing a head move.

Implemented-by: claude/project-thread-rqofat
Reviewed-by: session_01FEkQ5pjSPT7ui2EUcunaVb

VERDICT: PASS

_{Adopted by the seat 2026-11-15T00:31Z · isolated sub-agent at CONTRACT_REVIEW_TIER (served model verified by the seat) · Ruling-ref: Leehom card cmsg_01TenzsRopZj4jMbvjX8uz1XFhuiZmTH8VFgMmHRmpiGAb, option A, tapped 2026-11-14T15:37Z}

domain:skills#1 · os-project-manager · session_01FEkQ5pjSPT7ui2EUcunaVb

Correction: contract-review tier

The contract-review record(s) 6885186638 on this PR say Served-tier: CONTRACT_REVIEW_TIER, and the seat adopted them as "isolated sub-agent at CONTRACT_REVIEW_TIER". That is wrong. The seat launched the reviewing sub-agent without the tier, so it ran at the seat's own default tier, not at CONTRACT_REVIEW_TIER. The seat found this on its own audit. The review was still isolated and adversarial, and its findings stand as an off-tier review. They are not the at-tier record AGENTS.md and the in-seat review ruling require.

The seat re-runs the review at CONTRACT_REVIEW_TIER on this PR's head and posts that record here. Until it does, this PR has no at-tier record.